import { Code } from '~/components/text/code'
import { HelpLink } from '~/components/text/link'
import Endpoint from '~/components/api/endpoint'
import Request from '~/components/api/request'

export const meta = {
  editUrl: 'pages/docs/api/v2/api-docs-mdx/endpoints/certificates.mdx',
  lastEdited: '2019-10-17T14:44:04.000Z'
}

## Certificates

### List all the certificates

<Endpoint method="GET" url="/v3/now/certs" />

Retrieves a list of certificates issued for the authenticating user or
information about the certificate issued for the common name specified in the URL.

#### Response Parameters

| Key       | <HelpLink href="#api-basics/types" hasIcon>Type</HelpLink> | Description                      |
| --------- | ---------------------------------------------------------- | -------------------------------- |
| **certs** | <HelpLink href="#api-basics/types">List</HelpLink>         | The list of issued certificates. |

#### Certificate

This is the format of each item in the `certs` list.

| Key            | <HelpLink href="#api-basics/types" hasIcon>Type</HelpLink>    | Description                                                   |
| -------------- | ------------------------------------------------------------- | ------------------------------------------------------------- |
| **uid**        | <HelpLink href="#api-basics/types">ID</HelpLink>              | The unique identifier of the certificate.                     |
| **cns**        | <HelpLink href="#api-basics/types">List&lt;String></HelpLink> | The common names for which domain the certificate was issued. |
| **created**    | <HelpLink href="#api-basics/types">Date</HelpLink>            | The date when the certificate was created.                    |
| **expiration** | <HelpLink href="#api-basics/types">Date</HelpLink>            | The date when the certificate is going to expire.             |
| **autoRenew**  | <HelpLink href="#api-basics/types">Boolean</HelpLink>         | If the certificate is going to be automatically renewed.      |

##### Example Request

<Request url="https://api.zeit.co/v3/now/certs" auth />

##### Example Response

<Code lang="json">{`{
  "certs": [
    {
      "cns": ["testing.zeit.co", "*.zeit.co"],
      "uid": "oAjf6y9pxZgCJyQfrclN",
      "created": "2016-08-23T18:13:09.773Z",
      "expiration": "2016-12-16T16:00:00.000Z",
      "autoRenew": true
    }
  ]
}`}</Code>

### Get a single certificate

<Endpoint method="GET" url="/v3/now/certs/:id" />

Retrieves the information about the certificate issued for
certificate id specified in the URL.

#### Response Parameters

| Key            | <HelpLink href="#api-basics/types" hasIcon>Type</HelpLink>    | Description                                                   |
| -------------- | ------------------------------------------------------------- | ------------------------------------------------------------- |
| **uid**        | <HelpLink href="#api-basics/types">ID</HelpLink>              | The unique identifier of the certificate.                     |
| **cns**        | <HelpLink href="#api-basics/types">List&lt;String></HelpLink> | The common names for which domain the certificate was issued. |
| **created**    | <HelpLink href="#api-basics/types">Date</HelpLink>            | The date when the certificate was created.                    |
| **expiration** | <HelpLink href="#api-basics/types">Date</HelpLink>            | The date when the certificate is going to expire.             |
| **autoRenew**  | <HelpLink href="#api-basics/types">Boolean</HelpLink>         | If the certificate is going to be automatically renewed.      |

##### Example Request

<Request url="https://api.zeit.co/v3/now/certs/oAjf6y9pxZgCJyQfrclN" auth />

##### Example Response

<Code lang="json">{`{
  "cns": ["wow.zeit.co"],
  "uid": "oAjf6y9pxZgCJyQfrclN",
  "created": "2016-08-23T18:13:09.773Z",
  "expiration": "2016-12-16T16:00:00.000Z",
  "autoRenew": true
}`}</Code>

### Create a new certificate

<Endpoint method="POST" url="/v3/now/certs" />

Issues and stores a new certificate for the common names given in
the body using **Let's Encrypt**.

The body should contain \`domains\` array and it may contain \`renew\` field to renew an existing certificate.

#### Request Parameters

| Key         | <HelpLink href="#api-basics/types" hasIcon>Type</HelpLink>    | Required | Description                                                            |
| ----------- | ------------------------------------------------------------- | -------- | ---------------------------------------------------------------------- |
| **domains** | <HelpLink href="#api-basics/types">List&lt;String></HelpLink> | Yes      | A list of Common Names for which the certificate is being provisioned. |

#### Response Parameters

| Key            | <HelpLink href="#api-basics/types" hasIcon>Type</HelpLink> | Description                                      |
| -------------- | ---------------------------------------------------------- | ------------------------------------------------ |
| **uid**        | <HelpLink href="#api-basics/types">ID</HelpLink>           | The unique identifier of the issued certificate. |
| **created_at** | <HelpLink href="#api-basics/types">Date</HelpLink>         | The date when the certificate was created.       |

##### Example Request

<Request
  method="POST"
  url="https://api.zeit.co/v3/now/certs"
  headers={{
    'Content-Type': 'application/json'
  }}
  auth
  body={{
    domains: ['testing.zeit.co'],
    renew: true
  }}
/>

##### Example Response

<Code lang="json">{`{
  "uid": "zWsFytQUFlkUWaR7nWdwS7xR"
  "created_at": 2016-06-01T21:03:10.420Z"
}`}</Code>

### Submit a certificate

<Endpoint method="PUT" url="/v3/now/certs" />

Create a new certificate entry with a user-supplied certificate.

The body should contain `cert`, private `key`, and `ca` chain fields in PEM format.

#### Request Parameters

| Key      | <HelpLink href="#api-basics/types" hasIcon>Type</HelpLink> | Required | Description                |
| -------- | ---------------------------------------------------------- | -------- | -------------------------- |
| **ca**   | <HelpLink href="#api-basics/types">String</HelpLink>       | Yes      | PEM formatted CA chain.    |
| **cert** | <HelpLink href="#api-basics/types">String</HelpLink>       | Yes      | PEM formatted certificate. |
| **key**  | <HelpLink href="#api-basics/types">String</HelpLink>       | Yes      | PEM formatted private key. |

#### Response Parameters

| Key            | <HelpLink href="#api-basics/types" hasIcon>Type</HelpLink> | Description                                |
| -------------- | ---------------------------------------------------------- | ------------------------------------------ |
| **created_at** | <HelpLink href="#api-basics/types">Date</HelpLink>         | The date when the certificate was created. |

##### Example Request

<Request
  method="PUT"
  url="https://api.zeit.co/v3/now/certs"
  headers={{
    'Content-Type': 'application/json'
  }}
  auth
  body={{
    ca: 'PEM formatted CA chain',
    cert: 'PEM formatted certificate',
    key: 'PEM formatted private key'
  }}
/>

##### Example Response

<Code lang="json">{`{
  "created_at": 2016-06-01T21:03:10.420Z"
}`}</Code>

### Delete a certificate

<Endpoint method="DELETE" url="/v3/now/certs/:id" />

Delete an existing certificate entry. If the certificate entry was
removed successfully the endpoint will return with code **200** and
an empty body; Otherwise an error object is returned.

##### Example Request

<Request
  method="DELETE"
  url="https://api.zeit.co/v3/now/certs/zWsFytQUFlkUWaR7nWdwS7xR"
  auth
/>
